<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Create transform API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'put-transform.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/put-transform.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/put-transform.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/put-transform.html" rel="nofollow" target="_blank">../en/put-transform.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="transform-apis.html">Transform APIs</a></span>
»
<span class="breadcrumb-node">Create transform API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="transform-apis.html">« Transform APIs</a>
</span>
<span class="next">
<a href="delete-transform.html">Delete transform API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="put-transform"></a>Create transform API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>

<p>Instantiates a transform.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">PUT _transform/&lt;transform_id&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<p>If the Elasticsearch security features are enabled, you must have the following
built-in roles and privileges:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">transform_admin</code>
</li>
<li class="listitem">
<code class="literal">kibana_admin</code> (UI only)
</li>
<li class="listitem">
source index: <code class="literal">read</code>, <code class="literal">view_index_metadata</code>
</li>
<li class="listitem">
destination index: <code class="literal">read</code>, <code class="literal">create_index</code>, <code class="literal">manage</code> and <code class="literal">index</code>
</li>
<li class="listitem">
cluster: <code class="literal">monitor</code> (UI only)
</li>
</ul>
</div>
<p>For more information, see <a class="xref" href="security-privileges.html" title="Security privileges">Security privileges</a> and <a class="xref" href="built-in-roles.html" title="Built-in roles">Built-in roles</a>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<p>This API defines a transform, which copies data from source indices,
transforms it, and persists it into an entity-centric destination index. The
entities are defined by the set of <code class="literal">group_by</code> fields in the <code class="literal">pivot</code> object. You
can also think of the destination index as a two-dimensional tabular data
structure (known as a data frame). The ID for each document in the
data frame is generated from a hash of the entity, so there is a unique row
per entity. For more information, see <a class="xref" href="transforms.html" title="Transforming data"><em>Transforming data</em></a>.</p>
<p>When the transform is created, a series of validations occur to
ensure its success. For example, there is a check for the existence of the
source indices and a check that the destination index is not part of the source
index pattern. You can use the <code class="literal">defer_validation</code> parameter to skip these
checks.</p>
<p>Deferred validations are always run when the transform is started,
with the exception of privilege checks. When Elasticsearch security features are
enabled, the transform remembers which roles the user that created
it had at the time of creation and uses those same roles. If those roles do not
have the required privileges on the source and destination indices, the
transform fails when it attempts unauthorized operations.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>You must use Kibana or this API to create a transform.
            Do not put a transform directly into any
            <code class="literal">.transform-internal*</code> indices using the Elasticsearch index API.
            If Elasticsearch security features are enabled, do not give users any
            privileges on <code class="literal">.transform-internal*</code> indices. If you used transforms
            prior 7.5, also do not give users any privileges on
            <code class="literal">.data-frame-internal*</code> indices.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-path-parms"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;transform_id&gt;</code>
</span>
</dt>
<dd>
(Required, string)
Identifier for the transform. This identifier can contain lowercase
alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start
and end with alphanumeric characters.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-query-parms"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">defer_validation</code>
</span>
</dt>
<dd>
(Optional, boolean) When <code class="literal">true</code>, deferrable validations are not run. This
behavior may be desired if the source index does not exist until after the
transform is created.
</dd>
</dl>
</div>
</div>

<div class="section child_attributes">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">description</code>
</span>
</dt>
<dd>
(Optional, string) Free text description of the transform.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">dest</code>
</span>
</dt>
<dd>
<p>
(Required, object)
The destination for the transform.
</p>
<details open>
<summary class="title">Properties of <code class="literal">dest</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">index</code>
</span>
</dt>
<dd>
(Required, string)
The <em>destination index</em> for the transform.
</dd>
<dt>
<span class="term">
<code class="literal">pipeline</code>
</span>
</dt>
<dd>
(Optional, string)
The unique identifier for a <a class="xref" href="pipeline.html" title="Pipeline Definition">pipeline</a>.
</dd>
</dl>
</div>
</div>
</details>
</dd>
<dt>
<span class="term">
<code class="literal">frequency</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>)
The interval between checks for changes in the source indices when the
transform is running continuously. Also determines the retry interval in the
event of transient failures while the transform is searching or indexing. The
minimum value is <code class="literal">1s</code> and the maximum is <code class="literal">1h</code>. The default value is <code class="literal">1m</code>.
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">pivot</code>
</span>
</dt>
<dd>
<p>
(Required, object)
The method for transforming the data. These objects define the pivot function
<code class="literal">group by</code> fields and the aggregation to reduce the data.
</p>
<details open>
<summary class="title">Properties of <code class="literal">pivot</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">aggregations</code> or <code class="literal">aggs</code>
</span>
</dt>
<dd>
<p>
(Required, object)
Defines how to aggregate the grouped data. The following composite aggregations
are supported:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-avg-aggregation.html" title="Avg Aggregation">Average</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-weight-avg-aggregation.html" title="Weighted Avg Aggregation">Weighted average</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-cardinality-aggregation.html" title="Cardinality Aggregation">Cardinality</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-bucket-filter-aggregation.html" title="Filter Aggregation">Filter</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-geobounds-aggregation.html" title="Geo Bounds Aggregation">Geo bounds</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-geocentroid-aggregation.html" title="Geo Centroid Aggregation">Geo centroid</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-max-aggregation.html" title="Max Aggregation">Max</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-min-aggregation.html" title="Min Aggregation">Min</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-percentile-aggregation.html" title="Percentiles Aggregation">Percentiles</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-scripted-metric-aggregation.html" title="Scripted Metric Aggregation">Scripted metric</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-sum-aggregation.html" title="Sum Aggregation">Sum</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-metrics-valuecount-aggregation.html" title="Value Count Aggregation">Value count</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-pipeline-bucket-script-aggregation.html" title="Bucket Script Aggregation">Bucket script</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-pipeline-bucket-selector-aggregation.html" title="Bucket Selector Aggregation">Bucket selector</a>
</li>
</ul>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Transforms support a subset of the functionality in
composite aggregations. See <a class="xref" href="transform-limitations.html" title="Transform limitations">Limitations</a>.</p>
</div>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">group_by</code>
</span>
</dt>
<dd>
<p>
(Required, object)
Defines how to group the data. More than one grouping can be defined
  per pivot. The following groupings are supported:
</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a class="xref" href="search-aggregations-bucket-composite-aggregation.html#_terms" title="Terms">Terms</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-bucket-composite-aggregation.html#_histogram" title="Histogram">Histogram</a>
</li>
<li class="listitem">
<a class="xref" href="search-aggregations-bucket-composite-aggregation.html#_date_histogram" title="Date histogram">Date histogram</a>
</li>
</ul>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">max_page_search_size</code>
</span>
</dt>
<dd>
(Optional, integer)
Defines the initial page size to use for the composite aggregation for each
checkpoint. If circuit breaker exceptions occur, the page size is dynamically
adjusted to a lower value. The minimum value is <code class="literal">10</code> and the maximum is <code class="literal">10,000</code>.
The default value is <code class="literal">500</code>.
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">source</code>
</span>
</dt>
<dd>
<p>
(Required, object)
The source of the data for the transform.
</p>
<details open>
<summary class="title">Properties of <code class="literal">source</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">index</code>
</span>
</dt>
<dd>
(Required, string or array)
The <em>source indices</em> for the transform. It can be a single index, an index
pattern (for example, <code class="literal">"myindex*"</code>), an array of indices (for example,
<code class="literal">["index1", "index2"]</code>), or an array of index patterns (for example,
<code class="literal">["myindex1-*", "myindex2-*"]</code>.
</dd>
<dt>
<span class="term">
<code class="literal">query</code>
</span>
</dt>
<dd>
(Optional, object)
A query clause that retrieves a subset of data from the source index. See
<a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a>.
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">sync</code>
</span>
</dt>
<dd>
<p>
(Optional, object)
Defines the properties transforms require to run continuously.
</p>
<details open>
<summary class="title">Properties of <code class="literal">sync</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">time</code>
</span>
</dt>
<dd>
<p>
(Required, object)
Specifies that the transform uses a time field to synchronize the source and
destination indices.
</p>
<details open>
<summary class="title">Properties of <code class="literal">time</code></summary>
<div class="content">
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">delay</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>)
The time delay between the current time and the latest input data time. The
default value is <code class="literal">60s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">field</code>
</span>
</dt>
<dd>
<p>
(Required, string)
The date field that is used to identify new documents in the source.
</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>In general, it’s a good idea to use a field that contains the
<a class="xref" href="accessing-data-in-pipelines.html#accessing-ingest-metadata" title="Accessing Ingest Metadata Fields">ingest timestamp</a>. If you use a different field,
you might need to set the <code class="literal">delay</code> such that it accounts for data transmission
delays.</p>
</div>
</div>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>
</details>
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="put-transform-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/transform/apis/put-transform.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT _transform/ecommerce_transform
{
  "source": {
    "index": "kibana_sample_data_ecommerce",
    "query": {
      "term": {
        "geoip.continent_name": {
          "value": "Asia"
        }
      }
    }
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id"
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  },
  "description": "Maximum priced ecommerce data by customer_id in Asia",
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform",
    "pipeline": "add_timestamp_pipeline"
  },
  "frequency": "5m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "60s"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2152.console"></div>
<p>When the transform is created, you receive the following results:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "acknowledged" : true
}</pre>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="transform-apis.html">« Transform APIs</a>
</span>
<span class="next">
<a href="delete-transform.html">Delete transform API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>